UpdateGWorld

UpdateGWorld
Header:	QDOffscreen.h		Carbon status:	Supported

Changes the pixel depth, boundary rectangle, or color table for an existing offscreen graphics world.

GWorldFlags UpdateGWorld (
    GWorldPtr *offscreenGWorld, 
    SInt16 pixelDepth, 
    const Rect *boundsRect, 
    CTabHandle cTable, 
    GDHandle aGDevice, 
    GWorldFlags flags
);

offscreenGWorld: On input, a pointer to an existing offscreen graphics world; upon completion, the pointer to the updated offscreen graphics world.
pixelDepth: The pixel depth of the offscreen world; possible depths are 1, 2, 4, 8, 16, and 32 bits per pixel. If you specify 0 in this parameter, UpdateGWorld rescans the device list and uses the depth of the screen with the greatest pixel depth among all screens whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. If you specify 0 in this parameter, UpdateGWorld also copies the GDevice structure from this device to create an offscreen GDevice structure. The UpdateGWorld function ignores the value you supply for this parameter if you specify a GDevice structure in the aGDevice parameter.
boundsRect: The boundary rectangle and port rectangle for the offscreen pixel map. This also becomes the boundary rectangle for the GDevice structure, if NewGWorld creates one. If you specify 0 in the pixelDepth parameter, NewGWorld interprets the boundaries in global coordinates, with which it determines which screens intersect the rectangle. (NewGWorld then uses the pixel depth, color table, and GDevice structure from the screen with the greatest pixel depth from among all screens whose boundary rectangles intersect this rectangle.) Typically, your application supplies this parameter with the port rectangle for the onscreen window into which your application will copy the pixel image from this offscreen world.
cTable: A handle to a ColorTable structure. If you pass NULL in this parameter, UpdateGWorld uses the default color table for the pixel depth that you specify in the pixelDepth parameter; if you set the pixelDepth parameter to 0, UpdateGWorld copies and uses the color table of the graphics device with the greatest pixel depth among all graphics devices whose boundary rectangles intersect the rectangle that you specify in the boundsRect parameter. The UpdateGWorld function ignores the value you supply for this parameter if you specify a GDevice structure in the aGDevice parameter.
aGDevice: As an option, a handle to a GDevice structure whose pixel depth and color table you want to use for the offscreen graphics world. To use the pixel depth and color table that you specify in the pixelDepth and cTable parameters, set this parameter to NULL.
flags: Options available to your application. You can set a combination of the flags keepLocal, clipPix, stretchPix, and ditherPix. If you don’t wish to use any of these flags, specify 0. However, you should pass either clipPix or stretchPix to ensure that the pixel map is updated to reflect the new color table. See “GWorld Flags” for a description of the values you can use here.

function result

UpdateGWorld returns the gwFlagErr flag if UpdateGWorld was unsuccessful; in this case, the offscreen graphics world is left unchanged. Use the QDError function to help you determine why UpdateGWorld failed.

If UpdateGWorld is successful, it returns a combination of the flags described in “GWorld Flags”

DISCUSSION

You should call UpdateGWorld after every update event and whenever your windows move or change size.

If the LockPixels function reports that the Memory Manager has purged the base address for the offscreen pixel image, use UpdateGWorld to reallocate its memory. Then, reconstruct the pixel image or draw directly in a window instead of preparing the image in an offscreen graphics world.

In the flags parameter, specify the keepLocal flag, which keeps the offscreen pixel image in Macintosh main memory or returns the image to main memory if it had been previously cached. If you use UpdateGWorld without passing it the keepLocal flag, you allow the offscreen pixel image to be cached on a graphics accelerator card if one is present.

The UpdateGWorld function uses the following algorithm when updating the offscreen pixel image:

If the color table that you specify in the cTable parameter is different from the previous color table, or if the color table associated with the GDevice structure that you specify in the aGDevice parameter is different, Color QuickDraw maps the pixel values in the offscreen pixel map to the new color table.
If the value you specify in the pixelDepth parameter differs from the previous pixel depth, Color QuickDraw translates the pixel values in the offscreen pixel image to those for the new pixel depth.
If the rectangle you specify in the boundsRect parameter differs from, but has the same size as, the previous boundary rectangle, QuickDraw realigns the pixel image to the screen for optimum performance for the CopyBits function.
If the rectangle you specify in the boundsRect parameter is smaller than the previous boundary rectangle and you specify the clipPix flag, the pixel image is clipped along the bottom and right edges.
If the rectangle you specify in the boundsRect parameter is bigger than the previous boundary rectangle and you specify the clipPix flag, the bottom and right edges of the pixel image are undefined.
If the rectangle you specify in the boundsRect parameter is smaller than the previous boundary rectangle and you specify the stretchPix flag, the pixel image is reduced to the new size.
If the rectangle you specify in the boundsRect parameter is bigger than the previous boundary rectangle and you specify the stretchPix flag, the pixel image is stretched to the new size.
If the Memory Manager purged the base address for the offscreen pixel image, UpdateGWorld reallocates the memory, but the pixel image is lost. You must reconstruct it.

SPECIAL CONSIDERATIONS

The UpdateGWorld function may move or purge memory blocks in the application heap; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.